home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #1 / Amiga Plus CD - 2000 - No. 1.iso / Tools / Text / Edit / GoldED-Demo / installdata / golded / developer / syntax / examples / readme
Encoding:
Text File  |  1999-12-03  |  5.0 KB  |  99 lines
  1. PURPOSE
  2.  
  3.   Syntax parser example code.
  4.  
  5. COPYIGHT
  6.  
  7.   ©1999 Dietmar Eilert. All Rights Reserved.
  8.  
  9.   Dietmar Eilert
  10.   Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  11.   Phone: +49-(0)179-5987061 German/English
  12.   E-Mail: Dietmar.Eilert@post.rwth-aachen.de
  13.   E-Mail: dietmar_eilert@yahoo.de (alternative address)
  14.   WWW:    http://members.tripod.com/golded
  15.   Mirror: http://members.xoom.com/golded
  16.  
  17. ABOUT
  18.  
  19.   The  source  drawer  containes  four  fully  compilable  shared   libraries
  20.   implemented  for  DICE  demonstrating  how  one  can  write a syntax parser
  21.   library  (library  code  &  description  based  on  Matt  Dillon's  example
  22.   library): "Some knowledge in shared libraries is required to understand the
  23.   code. The basic thing to remember is (1) that a shared  library  is  NOT  a
  24.   normal  C  program,  and  (2)  the  interface calls MUST be reentrant, i.e.
  25.   multiple tasks can make a library call simultaniously".
  26.  
  27. BASICS
  28.  
  29.   Syntax parsers actually are libraries, loaded by the editor  at  run  time.
  30.   Syntax  parsers  are  expected to parse the lines of a text and to return a
  31.   syntax description to the editor. The editor is responsible for the display
  32.   and for keeping the syntax parser up-to-date. Every syntax parser will have
  33.   to implement a fixed set of library functions called by the  editor.  These
  34.   functions are described in "autodoc/scanlib.doc". The most important one is
  35.   ParseLine(): it is called by the editor if  it  is  looking  for  a  syntax
  36.   desciption  while  refreshing the display: The editor will pass a text line
  37.   to the parser, the parser will return  a  syntax  description.  This  basic
  38.   mechanism  is  supplemented  by  additional  library  calls to support high
  39.   performance syntax parsing (simple parsers may choose  to  ignore  most  of
  40.   them). Two classes of syntax parsers are supported:
  41.  
  42.   1. Context parser
  43.  
  44.   Context parsers are able to judge and highlight syntax elements  consisting
  45.   of  multiple  lines  (e.g. a comment). Context parsers are the most complex
  46.   parsers since they will have to judge every action performed by the editor:
  47.   deleting  the first line of a file might influence highlighting of the last
  48.   line. The editor will keep the parser up-to-date by "sending" notifies (ie.
  49.   calling a parser function). A context parsers should use a syntax chache in
  50.   order to speed up parsing: results of prior parser passes should be cached.
  51.   Context  parsers  tend to be slow. A context parser example is available as
  52.   "example_context".
  53.  
  54.   2. Non-context parser
  55.  
  56.   Non-context parsers  do  judge  single  lines  only.  They  are  unable  to
  57.   recognize syntax elements consisting of multiple lines. Non-context parsers
  58.   are considerably less complex than context parsers. Some of them will use a
  59.   syntax  cache  (consuming  memory), some of them are fast enough to provide
  60.   real-time parsing. Two examples found in the source drawer are  non-context
  61.   parsers  highlighting  C++  comments (C++ comments are introduced by a "//"
  62.   and terminated by the end of the line): the first example  "example_cached"
  63.   uses a cache, the second example "example_simple" doesn't use a cache.
  64.  
  65.   Generic syntax parsers
  66.  
  67.   While most syntax parsers are made for a specific  purpose  and  come  with
  68.   built-in  rules  and  dictionaries,  the  editor also supports configurable
  69.   parsers by providing a standard configuration dialog. This  dialog  can  be
  70.   used  to  specify keywords and other language details to be recognized. The
  71.   editor will pass the configuration details to the parser when it is started
  72.   (StartScanner).  The  parser  must specify its configurable elements in the
  73.   ParserData->pd_Properties field and set the SCPRB_GENERIC  flag  to  unlock
  74.   the  relevant  configuration  gadgets. Syntax parsers may also override the
  75.   editor's built-in configuration dialog with their own window by setting the
  76.   SCPRB_CONFIGWIN flag: the editor will then call the parser's SetupScanner()
  77.   function instead of showing the built-in configuration dialog. Have a  look
  78.   at  "example_generic" to learn more about programming a configurable syntax
  79.   parser.
  80.  
  81. FILES
  82.  
  83.   DEFS.H      parser independant header stuff   (do not change)
  84.   LIB.C       parser independant basic code     (do not change)
  85.   INIT.C      parser independant initialization (do not change)
  86.   TAG.A       parser dependant code
  87.   FUNCS.C     parser dependant code
  88.  
  89.   DEFS.H, LIB.C and INIT.C are parser independant  modules.  Do  not  change
  90.   these  files.  FUNCS.C is the parser code decribed by scanlib.doc. TAG.A is
  91.   the startup code with only one modifications required  if  used  for  other
  92.   projects: the name of the library. "TAG.A contains a subset of the standard
  93.   startup code LIB/AMIGA/C.A and assumes non-resident compilation  (i.e.  you
  94.   cannot use the -r option). This isn't a problem since the -r option doesn't
  95.   gain you anything as far as shared libraries  go.  The  individual  library
  96.   interface  routines are declared with the LibCall macro, defined in DEFS.H,
  97.   which ensures the small-data pointer is set  up  for  all  interface  calls
  98.   allowing use of the small-data model" (Matt Dillon).
  99.